Concept: Scripted plug-ins
Document scripts, as described in Creating and editing script palettes and scripts, allow scripts to be created, saved, and executed from a particular file using the Resource Manager. However, scripted plug-in objects allow scripts to be available in any Vectorworks file. The three types of plug-ins—menu commands (.vsm), tools (.vst), and objects (.vso)—allow scripts to be incorporated into a workspace as menu commands, tool palettes, and objects in resource libraries.
Plug-in objects created with scripts become custom items that can streamline and enhance the design/drafting process. They support the standard Vectorworks program core technologies such as snapping, classing, and advanced object editing, giving them essentially the same status as Vectorworks built-in object types.
Scripted plug-ins also provide enhanced portability and platform independence for scripts, allowing them to be easily moved to Vectorworks installations on either Mac or Windows systems. Drawings containing plug-in objects can be exchanged between users in different countries. The plug-ins can be localized for use in other countries by translating the names and strings that display.
How plug-ins work
Scripted plug-ins are saved as files. They combine script code with a plug-in "wrapper," an encoded header which defines the characteristics and behaviors of the plug-in. Information such as the category of the plug-in, properties which define how the plug-in is activated, or any other information needed by the plug-in to function within the Vectorworks application framework is included within the header.
Plug-in types
A key feature of scripted plug-ins is their smooth integration into the Vectorworks product interface. These menu commands, tools, and objects work just like any built-in Vectorworks tool, object, or menu item. Like built-in menu commands, scripted menu commands can be set to require certain file conditions such as 2D/3D view orientation or a selected set of items in order to activate. When a menu command or tool item is selected, the script and any information needed by the plug-in is loaded into memory, and the plug-in script executes. The Vectorworks program uses information provided by the plug-in to provide the user interactions (such as snapping) and file environment for the menu command or tool to perform its defined actions. Scripted tools, like their built-in counterparts, make use of the SmartCursor and other tool-centric Vectorworks program features.
Plug-in objects have characteristics of both tools and symbols. Plug-in objects can be added to a tool palette and resemble tool items, but in use, they place instances of the object in the file much like the symbol tool places symbols in a file. Object scripts can also be invoked through events that occur in the file. Placed object instances can be modified with the Object Info palette to edit the parametric values that are used to define the object, and these changes will cause the script defining the object to execute for the object to redraw. Global file changes which force a regeneration of the file can also cause the scripts of objects placed in the file to execute. These characteristics give plug-in objects enormous flexibility in how they can be displayed within a file.
Plug-in objects can also be used in conjunction with the Resource Manager to create preconfigured object instances that need minimal editing after placement. Libraries of different object configurations based on a single plug-in object can be easily created and retrieved through the Resource Manager.
There are four different types of plug-in objects: point, linear, rectangular, and path. Each type is different in how it is placed in the drawing and edited.
Point objects: Point plug-in objects are placed by a single click in the drawing to specify the location, and then a second click to set the rotation angle. Point plug-in objects cannot be edited (resized or rotated) with the cursor; they are edited using the Object Info palette.
Linear objects: Linear plug-in objects are placed with two clicks to define a line and its orientation. The object can be resized or rotated by clicking on a reshape handle at either end of the line. It can also be edited using the Object Info palette.
Rectangular objects: Rectangular plug-in objects are placed either by Center-line Placement (click to specify the location, click to set the length, and click to set the width) mode or by Edge Placement (click to set a corner, click to set the length, and click to set the width) mode. The object can be resized by dragging its selection handles, or edited through the Object Info palette.
Path objects: Path plug-in objects are created with a sequence of several clicks that define the vertex points along a path. There are two different types of path plug-in objects based on the type of path that is used. A 2D path plug-in object uses a polyline path and a 3D path plug-in object uses a 3D NURBS curve for its path. Path plug-in objects can be edited using the Reshape tool directly. They can also be edited through Modify > Edit Group, or the Object Info palette.
Plug-in file location
When the Vectorworks program launches, it searches for any scripted plug-in files and registers the information necessary to activate and manage the plug-ins. Include files are searched for in the same folder where the associated plug-in file is located.
The software searches for plug-ins in the following order and locations:
In the user’s Plug-Ins folder, or aliases or shortcuts in the user’s Plug-Ins folder
In the Vectorworks Plug-Ins folder and its subfolders
Aliases or shortcuts in the Vectorworks Plug-Ins folder that point to locations outside the Vectorworks hierarchy
The user’s Plug-Ins folder exists in a platform-specific location.
Windows: C:\Users\<Username>\AppData\Roaming\Nemetschek\Vectorworks\2024\Plug-Ins
Mac: /Users/<Username>/Library/Application Support/Vectorworks/2024/Plug-Ins
When plug-in files are first created, they are always placed in the user’s Plug-Ins folder.
When the Vectorworks program launches, or a workspace is activated, a plug-in is available in the current session only if it is located in the Plug-Ins folder, its subfolders, user’s Plug-Ins folder and subfolders, or folders referenced by aliases (Mac) or shortcuts (Windows).
If duplicate plug-in files exist in more than one location, the instance that occurs first in the folder hierarchy is the one that is used.
The flexibility of the plug-in file location provides an advantage when upgrading from a previous version of the software. Because third-party plug-ins can be stored in a folder separate from the application, they can easily be referenced when installing the upgrade. Copying the Plug-Ins folders to the current version’s folders, or referencing them with an alias or shortcut, is all that is required when upgrading.
